f90_unix_proc: UNIX Process Primitives Module

Contents

Name

f90_unix_proc - Module of Unix process primitives

Usage

USE F90_UNIX_PROC

This module contains part of a Fortran API to functions detailed in ISO/IEC 9945-1:1990 Portable Operating System Interface (POSIX) - Part 1: System Application Program Interface (API) [C Language].

The functions in this module are from Section 3: Process Primitives, excluding 3.3 Signals. The C language functions ABORT, ATEXIT, EXIT and SYSTEM are also provided by this module.

Error handling is described in F90_UNIX_ERRNO. Note that for procedures with an optional ERRNO argument, if an error occurs and ERRNO is not present, the program will be terminated.

Synopsis

Parameters
PID_KIND, WNOHANG, WUNTRACED.
Procedures
ABORT, ALARM, ATEXIT, EXECV, EXECVE, EXECVP, EXIT, FASTEXIT, FORK, PAUSE, SLEEP, SYSTEM, WAIT, WAITPID, WEXITSTATUS, WIFEXITED, WIFSIGNALED, WIFSTOPPED, WSTOPSIG, WTERMSIG.
Generic Procedures
EXECL, EXECLP.

Parameter Description

  INTEGER,PARAMETER :: PID_KIND
Integer kind for representing process IDs. 

  INTEGER,PARAMETER :: WNOHANG
Option bit for WAITPID indicating that the calling process should not wait for the child process to stop or exit. 

  INTEGER,PARAMETER :: WUNTRACED
Option bit for WAITPID indicating that status should be returned for stopped processes as well as terminated ones.

Procedure Description

  SUBROUTINE ABORT(message)

  CHARACTER*(*), OPTIONAL :: message
ABORT cleans up the i/o buffers and then terminates execution, producing a core dump on Unix systems. If MESSAGE is given it is written to logical unit 0 (zero) preceded by " abort:". 

  SUBROUTINE ALARM(SECONDS,SUBROUTINE,SECLEFT)

  INTEGER,INTENT(IN) :: SECONDS

  INTERFACE
        SUBROUTINE SUBROUTINE()
        END
  END INTERFACE
  OPTIONAL SUBROUTINE
  INTEGER,OPTIONAL,INTENT(OUT) :: SECLEFT
Establishes an "alarm" call to the procedure SUBROUTINE to occur after SECONDS seconds have passed, or cancels an existing alarm if SECONDS==0. If SUBROUTINE is not present, the previous associated of a subroutine with the alarm signal is left unchanged. If SECLEFT is present, it receives the number of seconds that were left on the preceding alarm or zero if there were no existing alarm.

If an alarm call is established with no handler (i.e. SUBROUTINE was not present on the first call) the process may be terminated when the alarm goes off. 

  SUBROUTINE ATEXIT(SUBROUTINE,ERRNO)
  INTERFACE
        SUBROUTINE SUBROUTINE()
        END
  END INTERFACE
  INTEGER,OPTIONAL,INTENT(OUT) :: ERRNO
Registers an argumentless subroutine for execution on normal termination of the program.

If the program terminates normally, all subroutines registered with ATEXIT will be invoked in reverse order of their registration. Normal termination includes using the F90_UNIX_PROC procedure EXIT, executing a Fortran STOP statement or executing a main program END statement. ATEXIT subroutines are invoked before automatic file closure.

If the program terminates due to an error or by using the F90_UNIX_PROC procedure FASTEXIT, these subroutines will not be invoked.

Possible errors include ENOMEM.

Note: The list of ATEXIT procedures registered via Fortran is separate from those registered via C; the latter will be invoked after all files have been closed. 

  SUBROUTINE EXECV(PATH,ARGV,LENARGV,ERRNO)

  CHARACTER*(*),INTENT(IN) :: PATH
  CHARACTER*(*),INTENT(IN) :: ARGV(:)
  INTEGER,INTENT(IN) :: LENARGV(:)
  INTEGER,OPTIONAL,INTENT(OUT) :: ERRNO
Executes the file PATH in place of the current process image; for full details see ISO/IEC 9945-1:1990 section 3.1.2. ARGV is the array of argument strings, LENARGV containing the desired length of each argument. If ARGV is not zero-sized, ARGV(1)(:LENARGV(1)) is passed as argument zero (i.e. the program name).

If LENARGV is not the same shape as ARGV, error EINVAL is raised (see F90_UNIX_ERRNO). Other possible errors include E2BIG, EACCES, ENAMETOOLONG, ENOENT, ENOTDIR, ENOEXEC, ENOMEM. 

  SUBROUTINE EXECVE(PATH,ARGV,LENARGV,ENV,LENENV,ERRNO)

  CHARACTER*(*),INTENT(IN) :: PATH
  CHARACTER*(*),INTENT(IN) :: ARGV(:)
  INTEGER,INTENT(IN) :: LENARGV(:)
  CHARACTER*(*),INTENT(IN) :: ENV(:)
  INTEGER,INTENT(IN) :: LENENV(:)
  INTEGER,OPTIONAL,INTENT(OUT) :: ERRNO
Similar to EXECV, with the environment strings specified by ENV and LENENV being passed to the new program; for full details see ISO/IEC 9945-1:1990 section 3.1.2.

If LENARGV is not the same shape as ARGV or LENENV is not the same shape as LENENV, error EINVAL is raised (see F90_UNIX_ERRNO). Other errors are the same as for EXECV. 

  SUBROUTINE EXECVP(FILE,ARGV,LENARGV,ERRNO)

  CHARACTER*(*),INTENT(IN) :: FILE
  CHARACTER*(*),INTENT(IN) :: ARGV(:)
  INTEGER,INTENT(IN) :: LENARGV(:)
  INTEGER,OPTIONAL,INTENT(OUT) :: ERRNO
The same as EXECV except that the program to be executed, FILE, is searched for using the PATH environment variable (unless it contains a slash character, in which case EXECVP is identical in effect to EXECV).

Errors are the same as for EXECV. 

  SUBROUTINE EXIT(STATUS)

  INTEGER,OPTIONAL :: STATUS
Terminate execution as if executing the END statement of the main program (or an unadorned STOP statement). If STATUS is given it is returned to the operating system (where applicable) as the execution status code. 

  SUBROUTINE FASTEXIT(STATUS)

  INTEGER,OPTIONAL :: STATUS
This provides the functionality of ISO/IEC 9945-1:1990 function _exit (section 3.2.2). There are two main differences between FASTEXIT and EXIT:
  1. When EXIT is called all open logical units are closed (as if by a CLOSE statement). With FASTEXIT this is not done, nor are any file buffers flushed, thus the contents and status of any file connected at the time of calling FASTEXIT are undefined.
  2. Subroutines registered with ATEXIT are not executed. 

  SUBROUTINE FORK(PID,ERRNO)

  INTEGER(PID_KIND),INTENT(OUT) :: PID
  INTEGER,OPTIONAL,INTENT(OUT) :: ERRNO
Creates a new process which is an exact copy of the calling process. In the new process, the value returned in PID is zero; in the calling process the value returned in PID is the process ID of the new (child) process.

Possible errors include EAGAIN and ENOMEM (see F90_UNIX_ERRNO). 

  SUBROUTINE PAUSE(ERRNO)

  INTEGER,INTENT(OUT) :: ERRNO
Suspends process execution until a signal is raised. If the action of the signal was to terminate the process, the process is terminated without returning from PAUSE. If the action of the signal was to invoke a signal handler (e.g. via ALARM), process execution continues after return from the signal handler.

If process execution is continued after a signal, ERRNO is set to EINTR. 

  PURE SUBROUTINE SLEEP(SECONDS,SECLEFT)

  INTEGER,INTENT(IN) :: SECONDS
  INTEGER,OPTIONAL,INTENT(OUT) :: SECLEFT
Suspends process execution for SECONDS seconds, or until a signal has been delivered. If SECLEFT is present, it receives the number of seconds remaining in the sleep time (zero unless the sleep was interrupted by a signal). 

  SUBROUTINE SYSTEM(STRING,STATUS,ERRNO)

  CHARACTER*(*),INTENT(IN) :: STRING
  INTEGER,OPTIONAL,INTENT(OUT) :: STATUS,ERRNO
Passes STRING to the command processor for execution. If STATUS is present it receives the completion status - this is the same status returned by "WAIT" and can be decoded with WIFEXITED etc. If ERRNO is present it receives the error status from the SYSTEM call itself.

Possible errors are those from FORK or EXECV. 

  SUBROUTINE WAIT(STATUS,RETPID,ERRNO)

  INTEGER,OPTIONAL,INTENT(OUT) :: STATUS
  INTEGER(PID_KIND),OPTIONAL,INTENT(OUT) :: RETPID
  INTEGER,OPTIONAL,INTENT(OUT) :: ERRNO
Wait for any child process to terminate (returns immediately if one has already terminated). See ISO/IEC 9945-1:1990 section 3.2.1 for full details.

If STATUS is present it receives the termination status of the child process. If RETPID is present it receives the process number of the child process.

Possible errors include ECHILD, EINTR (see F90_UNIX_ERRNO). 

  SUBROUTINE WAITPID(PID,STATUS,OPTIONS,RETPID,ERRNO)

  INTEGER(PID_KIND),INTENT(IN) :: PID
  INTEGER,OPTIONAL,INTENT(OUT) :: STATUS, RETPID, ERRNO
  INTEGER,OPTIONAL,INTENT(IN) :: OPTIONS
Wait for a particular child process to terminate (or for any one if PID.EQ.-1). If OPTIONS is not present it is as if it were present with a value of 0. See ISO/IEC 9945-1:1990 section 3.2.1 for full details.

Possible errors include ECHILD, EINTR, EINVAL (see F90_UNIX_ERRNO). 

  PURE INTEGER FUNCTION WEXITSTATUS(STAT_VAL)

  INTEGER,INTENT(IN) :: STAT_VAL
If WIFEXITED(STAT_VAL) is .TRUE., this function returns the low-order 8 bits of the status value supplied to EXIT or FASTEXIT by the child process. If the child process executed a STOP statement or main program END statement, the value will be zero. If WIFEXITED(STAT_VAL) is .FALSE., the function value is undefined. 

  PURE LOGICAL FUNCTION WIFEXITED(STAT_VAL)

  INTEGER,INTENT(IN) :: STAT_VAL
Returns .TRUE. if and only if the child process terminated by calling FASTEXIT, EXIT, or by executing a STOP statement or main program END statement. 

  PURE LOGICAL FUNCTION WIFSIGNALED(STAT_VAL)

  INTEGER,INTENT(IN) :: STAT_VAL
Returns .TRUE. if and only if the child process terminated by receiving a signal that was not caught. 

  PURE LOGICAL FUNCTION WIFSTOPPED(STAT_VAL)

  INTEGER,INTENT(IN) :: STAT_VAL
Returns .TRUE. if and only if the child process is stopped (and not terminated). Note that WAITPID must have been used with the WUNTRACED option to receive such a status value. 

  PURE INTEGER FUNCTION WSTOPSIG(STAT_VAL)

  INTEGER,INTENT(IN) :: STAT_VAL
If WIFSTOPPED(STAT_VAL) is .TRUE., this function returns the signal number that caused the child process to stop. If WIFSTOPPED(STAT_VAL) is .FALSE., the function value is undefined. 

  PURE INTEGER FUNCTION WTERMSIG(STAT_VAL)

  INTEGER,INTENT(IN) :: STAT_VAL
If WIFSIGNALED(STAT_VAL) is .TRUE., this function returns the signal number that caused the child process to terminate. If WIFSIGNALED(STAT_VAL) is .FALSE., the function value is undefined.

Generic Procedure Description

  SUBROUTINE EXECL(PATH,ARG0...,ERRNO)

  CHARACTER*(*),INTENT(IN) :: PATH
  CHARACTER*(*),INTENT(IN) :: ARG0...
  INTEGER,OPTIONAL,INTENT(OUT) :: ERRNO
Arguments are named ARG0, ARG1, etc. up to ARG20 (additional arguments may be provided in later releases). This function is the same as EXECV except that the arguments are provided individually instead of via an array; and because they are provided individually, there is no need to provide the lengths (the lengths being taken from each argument itself).

Errors are the same as for EXECV. 

  SUBROUTINE EX0ECLP(FILE,arguments,,ERRNO)

  CHARACTER*(*),INTENT(IN) :: FILE
  CHARACTER*(*),INTENT(IN) :: arguments
  INTEGER,OPTIONAL,INTENT(OUT) :: ERRNO
Arguments are named ARG0, ARG1, etc. up to ARG20 (additional arguments may be provided in later releases). This function is the same as EXECL except that determination of the program to be executed follows the same rules as EXECVP.

Errors are the same as for EXECV.

See Also

f90_unix_errno(3), f95(1), intro(3), nag_modules(3).

Bugs

Please report any bugs found to "support@nag.co.uk" or "infodesk@nag.com", along with any suggestions for improvements.